Scripting
Documentation
Changelog
Privacy
Documentation
Changelog
Privacy

Use with Toolbar Component

In Scripting, views can populate their navigation bar or toolbar area using either the original ToolBarProps object or the declarative component-based API that mirrors SwiftUI’s toolbar system. This document explains in detail how to use the Toolbar, ToolbarItem, ToolbarItemGroup, ToolbarSpacer, and DefaultToolbarItem components, including parameters, types, and usage patterns.

Overview

The toolbar property can be used in two ways:

  • By passing a ToolBarProps object
  • By passing a VirtualNode, which must be a <Toolbar> component

When using the component-based API, all toolbar content is declared inside a <Toolbar> container, and each item defines its placement explicitly. This provides clearer structure and more precise layout control, similar to SwiftUI.

1<List
2  toolbar={
3    <Toolbar>
4      {/* toolbar items here */}
5    </Toolbar>
6  }
7>
8  {/* main content */}
9</List>

Toolbar

The <Toolbar> component serves as a container for toolbar content. It does not define placement itself; instead, ToolbarItem and ToolbarItemGroup determine where items go.

Example

1<List
2  toolbar={
3    <Toolbar>
4      <ToolbarItem placement="topBarLeading">
5        <Button title="Close" action={dismiss} />
6      </ToolbarItem>
7      <ToolbarItem placement="topBarTrailing">
8        <Button title="Done" action={handleDone} />
9      </ToolbarItem>
10    </Toolbar>
11  }
12>
13  {/* content */}
14</List>

ToolbarItem

ToolbarItem represents a single toolbar element placed at a specific position.

Parameters

Parameter Type Default Description
placement ToolbarItemPlacement automatic Position of the item, such as topBarLeading, navigation, primaryAction
children VirtualNode required The item’s content, usually a button or text

Example

1<Toolbar>
2  <ToolbarItem placement="navigation">
3    <Button title="Back" action={() => navigation.pop()} />
4  </ToolbarItem>
5</Toolbar>

ToolbarItemGroup

ToolbarItemGroup allows multiple toolbar items to be grouped together in a single placement.

Parameters

Parameter Type Default Description
placement ToolbarItemPlacement automatic Placement for the entire group
children multiple VirtualNodes required The grouped toolbar items

Example

1<Toolbar>
2  <ToolbarItemGroup placement="topBarTrailing">
3    <Button title="Refresh" action={reload} />
4    <Button title="More" action={openMenu} />
5  </ToolbarItemGroup>
6</Toolbar>

ToolbarSpacer

ToolbarSpacer inserts empty space in a toolbar. It can be used to fine-tune layout between items.

Parameters

Parameter Type Default Description
sizing 'fixed' | 'flexible' flexible Determines whether the spacer expands or stays fixed
placement ToolbarItemPlacement automatic Placement for the spacer

Behavior

  • flexible: Expands to fill available space.
  • fixed: Adds a fixed separation between items.

Example

1<Toolbar>
2  <ToolbarItem placement="topBarTrailing">
3    <Button title="Edit" action={edit} />
4  </ToolbarItem>
5
6  <ToolbarSpacer sizing="fixed" />
7
8  <ToolbarItem placement="topBarTrailing">
9    <Button title="Save" action={save} />
10  </ToolbarItem>
11</Toolbar>

DefaultToolbarItem

DefaultToolbarItem inserts system-provided toolbar items, such as the sidebar toggle button or search button.

Parameters

Parameter Type Default Description
kind "sidebarToggle" | "search" | "title" required Specifies which system item to insert
placement ToolbarItemPlacement automatic Toolbar placement

Example

1<Toolbar>
2  <DefaultToolbarItem kind="search" placement="topBarTrailing" />
3</Toolbar>

Complete Example

1<NavigationStack>
2  <List
3    toolbar={
4      <Toolbar>
5
6        {/* Navigation button */}
7        <ToolbarItem placement="navigation">
8          <Button title="Back" action={navigation.pop} />
9        </ToolbarItem>
10
11        {/* Title */}
12        <DefaultToolbarItem kind="title" />
13
14        {/* Trailing group */}
15        <ToolbarItem placement="topBarTrailing">
16          <Button title="Edit" action={edit} />
17        </ToolbarItem>
18        <ToolbarSpacer sizing="fixed" />
19        <ToolbarItem placement="topBarTrailing">
20          <Button title="Done" action={finish} />
21        </ToolbarItem>
22
23        {/* Bottom bar item */}
24        <ToolbarItem placement="bottomBar">
25          <Button title="Help" action={showHelp} />
26        </ToolbarItem>
27
28      </Toolbar>
29    }
30  >
31    {/* content */}
32  </List>
33</NavigationStack>

Relationship with ToolBarProps

Method Description
toolbar={{ topBarTrailing: <Button/> }} Simple and declarative for straightforward scenarios
toolbar={<Toolbar>...</Toolbar>} More explicit, structured, and ideal for complex layouts

Both approaches remain fully supported. When a VirtualNode is passed, it must be a <Toolbar> component to ensure proper layout interpretation.

Outline